openapi: 3.0.1
info:
  title: Scope Assignments API
  description: Associates compatible objects with Hierarchical Scopes in Hyperproof.
  version: '1.0'
servers:
  - url: https://api.hyperproof.app/v1/scopeassignments
    description: Hyperproof US
  - url: https://api.hyperproofgov.app/v1/scopeassignments
    description: Hyperproof Gov
  - url: https://api.hyperproof.eu/v1/scopeassignments
    description: Hyperproof EU
security:
  - oauth2: []
paths:
  /:
    post:
      summary: Scope Assigments
      description: >
        `POST /`


        #### Description


        Creates or updates hiearchical scope assignments in a Hyperproof
        organization.
      operationId: add-scope-assignments
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HierarchicalScopeAssignmentPost'
            example:
              - objectType: control
                objectId: 6c006c16-9349-4df2-80be-64895c27d7bb
                scopeIds:
                  - 2128c0da-140e-460d-974c-8cd20401afbc
                  - ef11b12c-3b75-4a19-b212-72dcbe010fe7
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HierarchicalScopeAssignmentResponse'
              example:
                controls:
                  - id: d88d505d-5199-11ee-a644-522476618ae8
                    orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                    controlType: scopeAssignment
                    controlIdentifier: SOC2-P4.1.1_Legal
                    name: >-
                      Include in the privacy notice the use of collected
                      personal information
                    scopeName: Legal
                    description: >-
                      The privacy notice identifies the use of collected
                      personal information.
                    notes: ''
                    domainId: d7cf0a26-5199-11ee-a644-522476618ae8
                    domainName: Privacy
                    freshnessPolicy: manual
                    freshForDuration: PT720H
                    freshness: fresh
                    freshAsOfDate: 2025-01-12T18:26:10.00.5365Z
                    freshAsOfNote: Initial freshness set
                    implementation: inProgress
                    testingStatus: effective
                    testingDeficiency: []
                    computeTestingStatus: false
                    automation: partial
                    health: notAvailable
                    overrideHealth: false
                    owner:
                      id: d2363cab-5199-11ee-a644-522476618ae8
                      type: activeUser
                      userId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                      email: jane.doe@example.com
                      givenName: Jane
                      surname: Doe
                      language: en
                      locale: US
                      timeZone: America/Los_Angeles
                      status: active
                    customFields:
                      - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                        fieldName: Sponsor
                        fieldType: text
                        textValue: John Smith
                    status: active
                    createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                    createdOn: '2023-09-12T06:26:10.0000000+00:00'
                    updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                    updatedOn: '2023-09-12T06:26:10.0000000+00:00'
                    permissions: []
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://accounts.hyperproof.app/oauth/token
          scopes:
            scope.read: Grants read access to scopes
            scope.update: Grants update access to scopes
  schemas:
    Control:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the control
        orgId:
          type: string
          description: The unique identifier for the organization
        controlType:
          type: string
          description: Type of control
          enum:
            - simple
            - parent
            - scopeAssignment
        controlIdentifier:
          type: string
          description: >-
            The human readable unique identifier for the control within the
            organization
        name:
          type: string
          description: The name of the control
        teamName:
          type: string
          description: >-
            This field is deprecated and will be removed in a future version.
            Use `scopeName` instead
          deprecated: true
        scopeName:
          type: string
          description: >-
            Name of the scope associated with the control populated if the
            'controlType' is 'scopeAssignment'
        description:
          type: string
          description: The description of the control
        notes:
          type: string
          description: Additional notes about the control
        domainId:
          type: string
          description: The unique identifier of the domain
        domainName:
          type: string
          description: The name of the domain
        freshnessPolicy:
          $ref: '#/components/schemas/FreshnessPolicy'
        freshForDuration:
          type: string
          description: The duration after which control becomes stale
        freshness:
          $ref: '#/components/schemas/Freshness'
        freshAsOfDate:
          type: string
          description: The date when freshness was last marked 'fresh'
        freshAsOfNote:
          type: string
          description: The note populated when the control was marked fresh
        implementation:
          type: string
          description: Implementation status
          enum:
            - unknown
            - notStarted
            - inProgress
            - completed
        testingStatus:
          type: string
          description: Testing status
          enum:
            - notTested
            - inProgress
            - effective
            - ineffective
        testingDeficiency:
          type: array
          description: >-
            Design deficiency: The control, as designed, is inadequate to meet
            its intended objective. Operation deficiency: The control’s design
            is sound, but it is not being executed or followed as intended in
            practice.
          items:
            type: string
            enum:
              - design
              - operation
        computeTestingStatus:
          type: boolean
          description: Whether testing status is computed automatically
        automation:
          type: string
          description: >-
            Determines whether this control can be automated and its current
            status
          enum:
            - notStarted
            - partial
            - fullyAutomated
            - cantAutomate
        health:
          type: string
          description: Whether the health status is available and its current status
          enum:
            - critical
            - atRisk
            - healthy
            - notAvailable
        overrideHealth:
          type: boolean
          description: Whether health status is overridden
        owner:
          $ref: '#/components/schemas/User'
        groupId:
          type: string
          description: The unique identifier of the group assigned to the control
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldObjectValue'
        status:
          $ref: '#/components/schemas/ObjectStatus'
        createdBy:
          type: string
          description: The unique identifier of the user who created the control
        createdOn:
          type: string
          description: The date the control was created (ISO-8601 format)
        updatedBy:
          type: string
          description: The unique identifier of the user who last updated the control
        updatedOn:
          type: string
          description: The date the control was updated (ISO-8601 format)
        permissions:
          type: array
          description: List of permissions the API user has on the control
          items:
            type: string
        _isPartialData:
          type: boolean
          description: >-
            This is true when the user does not have read permissions on the
            control
      example:
        id: d88d505d-5199-11ee-a644-522476618ae8
        orgId: ce83e3cd-5199-11ee-a644-522476618ae8
        controlType: scopeAssignment
        controlIdentifier: SOC2-P4.1.1_Legal
        name: >-
          Include in the privacy notice the use of collected personal
          information
        scopeName: Legal
        description: >-
          The privacy notice identifies the use of collected personal
          information.
        notes: ''
        domainId: d7cf0a26-5199-11ee-a644-522476618ae8
        domainName: Privacy
        freshnessPolicy: manual
        freshForDuration: PT720H
        freshness: fresh
        freshAsOfDate: 2025-01-12T18:26:10.00.5365Z
        freshAsOfNote: Initial freshness set
        implementation: inProgress
        testingStatus: effective
        testingDeficiency: []
        computeTestingStatus: false
        automation: partial
        health: notAvailable
        overrideHealth: false
        owner:
          id: d2363cab-5199-11ee-a644-522476618ae8
          type: activeUser
          userId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
          email: jane.doe@example.com
          givenName: Jane
          surname: Doe
          language: en
          locale: US
          timeZone: America/Los_Angeles
          status: active
        customFields:
          - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
            fieldName: Sponsor
            fieldType: text
            textValue: John Smith
        status: active
        createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        createdOn: '2023-09-12T18:26:10.005365Z'
        updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        updatedOn: '2023-09-12T18:26:10.005365Z'
        permissions: []
    FreshnessPolicy:
      type: string
      description: >-
        The freshness policy of an object. Set to 'manual' with a
        'freshAsOfDate' value otherwise 'freshness' will be set to 'unknown'.
      enum:
        - none
        - manual
    Freshness:
      type: string
      description: >-
        The freshness status of an object. Cannot be set if 'freshnessPolicy' is
        'none' and 'freshAsOfDate' is null.
      enum:
        - noFreshness
        - fresh
        - expired
        - unknown
    User:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the user within the organization
          example: string
        type:
          type: string
          description: Type of Hyperproof user
          enum:
            - activeUser
            - deactivatedUser
            - contact
            - serviceAccount
            - deactivatedServiceAccount syncServiceAccount
            - deactivatedSyncServiceAccount
        userId:
          type: string
          description: Unique identifier for the user across all Hyperproof organizations
        email:
          type: string
          description: The email address of the user
        givenName:
          type: string
          description: The given name of the user
        surname:
          type: string
          description: The surname of the user
        language:
          type: string
          description: The language of the user
        locale:
          type: string
          description: The locale of the user
        timeZone:
          type: string
          description: The time zone of the user
        title:
          type: string
          description: The title of the user
        status:
          type: string
          description: The status of the user
          enum:
            - active
            - archived
            - deleted
            - pending
            - canceled
      example:
        id: d2363cab-5199-11ee-a644-522476618ae8
        type: activeUser
        userId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        email: jane.doe@example.com
        givenName: Jane
        surname: Doe
        language: en
        locale: US
        timeZone: America/Los_Angeles
        status: active
    CustomFieldObjectValue:
      type: array
      items:
        type: object
        properties:
          fieldId:
            type: string
            description: Unique identifier for the custom field
          fieldName:
            type: string
            description: Name of the custom field
          fieldType:
            type: string
            description: Type of field
            enum:
              - text
              - number
              - date
              - user
              - textSingleSelect
              - textMultiSelect
          numberFormat:
            type: string
            description: Format if the field type is `number`
            enum:
              - decimal
              - percentage
          textValue:
            type: string
            description: Value if the field type is `text`
          numberValue:
            type: number
            description: Value if the field type is `number`
          dateValue:
            type: string
            description: Value if the field type is `date`
          userValue:
            type: string
            description: Value if the field type is `user`
          selection:
            type: string
            description: Value for `textSingleSelect`
          selections:
            type: array
            description: List of values for `textMultiSelect`
            items:
              type: string
    ObjectStatus:
      type: string
      description: The status of the object
      enum:
        - active
        - archived
    ObjectType:
      type: string
      description: The type of the object.
      enum:
        - audit
        - connection
        - control
        - controlScope
        - domain
        - freshnessHistory
        - exportFile
        - label
        - organization
        - organizationUser
        - policy
        - program
        - proof
        - request
        - requirement
        - risk
        - riskRegister
        - section
        - task
        - scope
        - template
        - user
    HierarchicalScopeAssignmentPost:
      type: array
      items:
        type: object
        properties:
          objectType:
            $ref: '#/components/schemas/ObjectType'
          objectId:
            type: string
            description: >-
              The unique identifier of the object which will be associated with
              one or more scopes
          scopeIds:
            type: array
            description: >-
              The unique identifiers of the scopes which will be associated with
              the object
            items:
              type: string
      example:
        - objectType: control
          objectId: 6c006c16-9349-4df2-80be-64895c27d7bb
          scopeIds:
            - 2128c0da-140e-460d-974c-8cd20401afbc
            - ef11b12c-3b75-4a19-b212-72dcbe010fe7
    HierarchicalScopeAssignmentResponse:
      type: object
      properties:
        controls:
          type: array
          items:
            $ref: '#/components/schemas/Control'
      example:
        controls:
          - id: d88d505d-5199-11ee-a644-522476618ae8
            orgId: ce83e3cd-5199-11ee-a644-522476618ae8
            controlType: scopeAssignment
            controlIdentifier: SOC2-P4.1.1_Legal
            name: >-
              Include in the privacy notice the use of collected personal
              information
            scopeName: Legal
            description: >-
              The privacy notice identifies the use of collected personal
              information.
            notes: ''
            domainId: d7cf0a26-5199-11ee-a644-522476618ae8
            domainName: Privacy
            freshnessPolicy: manual
            freshForDuration: PT720H
            freshness: fresh
            freshAsOfDate: 2025-01-12T18:26:10.00.5365Z
            freshAsOfNote: Initial freshness set
            implementation: inProgress
            testingStatus: effective
            testingDeficiency: []
            computeTestingStatus: false
            automation: partial
            health: notAvailable
            overrideHealth: false
            owner:
              id: d2363cab-5199-11ee-a644-522476618ae8
              type: activeUser
              userId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
              email: jane.doe@example.com
              givenName: Jane
              surname: Doe
              language: en
              locale: US
              timeZone: America/Los_Angeles
              status: active
            customFields:
              - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                fieldName: Sponsor
                fieldType: text
                textValue: John Smith
            status: active
            createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
            createdOn: '2023-09-12T18:26:10.005365Z'
            updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
            updatedOn: '2023-09-12T18:26:10.005365Z'
            permissions: []
